{
 "metadata": {
  "signature": "sha256:c256980086fb5c190f6e55ed42d12ab3ddd63e957d080e72235fd689d7ffc5b3"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Scripting Mayavi 2\n",
      "==================\n",
      "\n",
      "||\\<\\#80FF80\\> This page presents scripting Mayavi2 using the advanced,\n",
      "object-oriented API. Mayavi2 has recently acquired an easy-to-use,\n",
      "thought maybe not as powerful, scripting module: mlab. You are invited\n",
      "to refer to the\n",
      "[section](http://code.enthought.com/projects/mayavi/docs/development/mayavi/html/mlab.html)\n",
      "of [Mayavi2 user\n",
      "guide](http://code.enthought.com/projects/mayavi/docs/development/mayavi/html/).\n",
      "Reading this page will give you a deeper understanding of how Mayavi2\n",
      "works, and it complements the user guide. ||\n",
      "\n",
      "Introduction\n",
      "------------\n",
      "\n",
      "To script !MayaVi2, you need (at least):\n",
      "\n",
      "`*\u00a0your\u00a0favorite\u00a0text\u00a0editor;`\\\n",
      "`*\u00a0python\u00a0installed\u00a0;-)`\\\n",
      "`*\u00a0!MayaVi2\u00a0installed\u00a0;-)`\n",
      "\n",
      "Scripting !MayaVi2 is quite simple because !MayaVi2 is written in python\n",
      "and based on TVTK, which eases the uses of all VTK objects.\n",
      "\n",
      "In the following, you'll be learned how to script and use !MayaVi2\n",
      "modules and filters.\n",
      "\n",
      "Modules can be split in two parts:\n",
      "\n",
      "`*\u00a0modules\u00a0which\u00a0do\u00a0not\u00a0interact\u00a0with\u00a0VTK\u00a0data,\u00a0and\u00a0are\u00a0seldom\u00a0modified/handled\u00a0(Outline,\u00a0Axes,\u00a0!OrientationAxes\u00a0and\u00a0Text).\u00a0These\u00a0are\u00a0called\u00a0the\u00a0\"basic\"\u00a0modules.\u00a0Although\u00a0color\u00a0bar\u00a0is\u00a0not\u00a0strictly\u00a0speaking\u00a0a\u00a0module,\u00a0it\u00a0will\u00a0be\u00a0presented\u00a0here.\u00a0Setting\u00a0a\u00a0few\u00a0parameters\u00a0for\u00a0rendering\u00a0your\u00a0scene\u00a0will\u00a0be\u00a0also\u00a0presented.`\n",
      "\n",
      "`*\u00a0modules\u00a0which\u00a0do\u00a0interact\u00a0with\u00a0VTK\u00a0data,\u00a0and\u00a0those\u00a0you\u00a0want\u00a0to\u00a0play\u00a0with\u00a0(i.e.\u00a0all\u00a0the\u00a0remainder\u00a0modules\u00a0;-).`\n",
      "\n",
      "Before starting, let's see the \"main template\" of a !MayaVi2 script\n",
      "written in python.\n",
      "\n",
      "Main template: create your MayaVi2 class\n",
      "----------------------------------------\n",
      "\n",
      "A !MayaVi2 script should contain at least the following few lines:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#! /usr/bin/env python\n",
      "\n",
      "from enthought.mayavi.app import Mayavi\n",
      "\n",
      "class MyClass(Mayavi):\n",
      "    \n",
      "    def run(self):\n",
      "        script = self.script\n",
      "        # `self.script` is the MayaVi Script interface (an instance of\n",
      "        # enthought.mayavi.script.Script) that is created by the\n",
      "        # base `Mayavi` class.  Here we save a local reference for\n",
      "        # convenience.\n",
      "  \n",
      "        ## import any Mayavi modules and filters you want (they must be done here!)\n",
      "        .../...\n",
      "\n",
      "        script.new_scene()                      # to create the rendering scene\n",
      "\n",
      "        ## your stuff (modules, filters, etc) here\n",
      "        .../...\n",
      "\n",
      "if __name__ == '__main__':\n",
      "    \n",
      "    mc = MyClass()\n",
      "    mc.main()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Adding modules or filters is quite simple: you have to import it, and\n",
      "then add it to your !MayaVi2 class.\n",
      "\n",
      "To add a module, type:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.foo_module import FooModule\n",
      ".../...\n",
      "mymodule = FooModule()\n",
      "script.add_module(mymodule)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "To add a filter, type:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.filters.bar_filter import BarFilter\n",
      ".../...\n",
      "myfilter = BarFilter()\n",
      "script.add_filter(myfilter)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Notice the used syntax: for modules for example, foo\\_module is the\n",
      "foo\\_module python file (without the extension .py) in the subdirectory\n",
      "module/ of mayavi/ directory (lower case, underscore); this file\n",
      "contains the class FooModule (no underscore, capitalized name).\n",
      "\n",
      "But first of all, before rendering your scene with the modules and the\n",
      "filters you want to use, you have to load some data, of course.\n",
      "\n",
      "Loading data\n",
      "------------\n",
      "\n",
      "You have the choice between:\n",
      "\n",
      "`*\u00a0create\u00a0a\u00a03D\u00a0data\u00a0array,\u00a0for\u00a0scalars\u00a0data\u00a0(for\u00a0vectors\u00a0data,\u00a0you\u00a0have\u00a0to\u00a0use\u00a0a\u00a04D\u00a0scalars\u00a0data,\u00a0i.e.\u00a0a\u00a03D\u00a0scalar\u00a0data\u00a0for\u00a0each\u00a0component)\u00a0and\u00a0load\u00a0it\u00a0with\u00a0!ArraySource\u00a0method;`\n",
      "\n",
      "`*\u00a0load\u00a0a\u00a0data\u00a0file\u00a0with\u00a0!FileReader\u00a0methods.`\n",
      "\n",
      "### Loading data from array using ArraySource method\n",
      "\n",
      "For example, we will create a 50\\*50\\*50 3D (scalar) array of a product\n",
      "of cosinus & sinus functions.\n",
      "\n",
      "To do this, we need to load the appropriate modules:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import scipy\n",
      "from scipy import ogrid, sin, cos, sqrt, pi\n",
      "\n",
      "from enthought.mayavi.sources.array_source import ArraySource\n",
      "\n",
      "Nx = 50\n",
      "Ny = 50\n",
      "Nz = 50\n",
      "\n",
      "Lx = 1\n",
      "Ly = 1\n",
      "Lz = 1\n",
      "\n",
      "x, y, z = ogrid[0:Lx:(Nx+1)*1j,0:Ly:(Ny+1)*1j,0:Lz:(Nz+1)*1j]\n",
      "\n",
      "# Strictly speaking, H is the magnetic field of the \"transverse electric\" eigenmode m=n=p=1\n",
      "# of a rectangular resonator cavity, with dimensions Lx, Ly, Lz\n",
      "Hx = sin(x*pi/Lx)*cos(y*pi/Ly)*cos(z*pi/Lz)\n",
      "Hy = cos(x*pi/Lx)*sin(y*pi/Ly)*cos(z*pi/Lz)\n",
      "Hz = cos(x*pi/Lx)*cos(y*pi/Ly)*sin(z*pi/Lz)\n",
      "Hv_scal = sqrt(Hx**2 + Hy**2 + Hz**2)\n",
      "\n",
      "# We want to load a scalars data (Hv_scal) as magnitude of a given 3D vector (Hv = {Hx, Hy, Hz})\n",
      "# Hv_scal is a 3D scalars data, Hv is a 4D scalars data\n",
      "src = ArraySource()\n",
      "src.scalar_data = Hv_scal # load scalars data\n",
      "\n",
      "# To load vectors data\n",
      "# src.vector_data = Hv"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Loading data from file using FileReader methods\n",
      "\n",
      "To load a VTK data file, say heart.vtk file in mayavi/examples/data/\n",
      "directory, simply type:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.sources.vtk_file_reader import VTKFileReader\n",
      "\n",
      "src = VTKFileReader()\n",
      "src.initialize(\"heart.vtk\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Note: Files with .vtk extension are called \"legacy VTK\" files. !MayaVi2\n",
      "can read a lot of other files formats (XML, files from Ensight, Plot3D\n",
      "and so on). For example, you can load an XML file (with extension .vti,\n",
      ".vtp, .vtr, .vts, .vtu, etc) using VTKXML!FileReader method.\n",
      "\n",
      "### Add the source to your MayaVi2 class\n",
      "\n",
      "Then, once your data are loaded using one of the two methods above, add\n",
      "the source with the add\\_source() method in the body of the class\n",
      "!MyClass (after script.new\\_scene):"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "script.add_source(src)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The four basic modules Outline, Axes, !OrientationAxes and Text will be presented now.\n",
      "\n",
      "## Basic Modules\n",
      "\n",
      "See the [:Cookbook/MayaVi/ScriptingMayavi2/BasicModules: Basic Modules] wiki page.\n",
      "\n",
      "## Main Modules\n",
      "\n",
      "See the [:Cookbook/MayaVi/ScriptingMayavi2/MainModules: Main Modules] wiki page.\n",
      "\n",
      "## Filters\n",
      "\n",
      "See the [:Cookbook/MayaVi/ScriptingMayavi2/Filters: Filters] wiki page."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}